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STATEMENT  OF  THE  PROBLEM  STUDIED 
Overview  Of  The  Problem: 


Software  has  a  limited  lifetime  of  usefulness,  because  as 
existing  software  ages,  support  becomes  more  difficult.  Major 
factors  in  determining  when  to  replace  rather  than  maintain 
software  are  1)  the  cost  of  training  new  personnel  to  maintain 
that  software,  and  2)  the  time  required  to  train  those  personnel. 
Modification  or  repair  is  made  easier  by  accurate  documentation. 
By  providing  automatic  techniques  of  documentation  generation, 
the  useful  lifetime  of  a  software  system  may  be  extended  as 
accurate  information  about  the  current  state  of  the  software  is 
made  available. 

The  domain  of  problems  our  research  addressed  included  looking 
into  the  various  weaknesses  and  vulnerabilities  of  software  and 
associated  documentation  as  the  software  ages. 

Approach : 

The  approach  of  this  effort  was  to  explore  and  select  methods  of 
documentation  that  automatically  extract  and  display  program 
logic  (and  more)  from  source  code,  thereby  extending  the  useful 
lifetime  of  software  systems.  The  research  concentrated  on 
developing  documentation  directly  from  the  source  code,  not  from 
sources  that  had  been  modified  for  documentation  generation 
purposes.  (These  modifications  are  often  called  "signals" 
embedded  in  the  code.) 

Goals  t 

The  goals  of  the  research  were  to: 

1.  Research  techniques  specifically  appropriate  to  the 
software  maintenance  environment,  as  contrasted  with 
methods  commonly  used  in  development.  This  research 
resulted  in  a  comprehensive  set  of  information 
requirements  that  were  needed  to  create  that 
documentation . 


2. 


3. 


Determine  the  design  of  a  general  documentation  language, 
focusing  on  being  able  to  handle  a  selected  class  of 
languages,  using  the  proposed  approach  (structured  in  the  _ 
three  categories  of  preprocessor,  compiler, 
postprocessor) . 


Determine  if  the  proposed  approach  could  be  implemented  to  i 
automatically  transform  programming  language  source  into 
documentation,  without  requiring  special  signaling  in  the 
source  code. 
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These  goals  mapped  cleanly  to  the  multi-phase  approach  desired. 
SUMMARY  OF  IMPORTANT  RESULTS 
Goals : 


At  this  time,  the  end  of  the  contract,  we  believe  that  we  have 
met  our  goals  as  follows: 

1.  The  research  into  documentation  methodologies  in  use  today 
successfully  led  to  the  knowledge  of  the  documentation 
requirements  perceived  relevant  to  and  by  maintenance 
programmers . 

2.  A  general  documentation  grammar  was  developed,  containing 
all  features  of  the  selected  class  of  target  languages. 
This  grammar  was  implemented,  i.e.  a  compiler  was  built 
for  it,  as  the  centerpiece  to  a  prototype  maintenance 
tool . 

3.  The  3 -phase  design  was  implemented;  the  DL  compiler  is 
essentially  complete,  the  postprocessor  for  modified  NS 
Diagrams  is  complete,  and  research  and  design  for  a 
FORTRAN  to  DL  preprocessor  is  essentially  complete.  As 
such,  the  prototype  accepts  working  C  code  and  generates 
NS  Diagrams  for  it. 

Important  Results: 

Work  on  this  project  led  to  some  interesting  conclusions.  The 
first  of  these  was  the  determination  that  none  of  the 
methodologies  in  use  today  is  really  optimal  in  its  utility  to 
maintenance  programmers.  While  NS  Diagrams  and  others  are 
familiar  to  programmers  and  to  many  knowledgeable  users,  the 
optimal  tool  would  provide  a  new  methodology  that  provided 
graphics,  text,  detail,  overview,  static  structure,  and  dynamic 
dataflow  all  in  a  visually-appealing,  user-friendly  way. 

The  second  conclusion  is  that  the  generality  requirement  is 
indeed  a  requirement,  not  just  a  consideration  of  interest. 
Programmers  working  with  different  languages  have  widely 
different  perceptions  about  what  is  useful  documentation.  Thus  a 
documentation  tool  that  provided  only  one  type  of  documentation 
would  not  solve  the  problem. 


PUBLICATIONS  AND  TECHNICAL  REPORTS  PUBLISHED 

A  paper  titled  "Documentation  in  a  Software  Maintenance 
Environment”  was  published  by,  and  presented  at,  the  Conference 
on  Software  Maintenance  (CSM-88). 


Page  3 


The  project  Interim  Technical  Report,  "Documentation  in  a 
Software  Maintenane  Environment",  is  available  through  DTIC,  AD 
number:  ADA  185  892. 

The  project  Final  Technical  Report,  "Automatic  Documentation 
Methodologies  for  Software  Maintenance",  is  nearing  completion 
and  will  be  submitted  for  inclusion  in  DTIC  holdings. 
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